Summary

Introduces CachingParseFileHandler that decorates ParseFileHandler to cache parsed document AST, avoiding re-parsing unchanged files.

Features

• Content-hash based caching: Detects unchanged files via xxh128 hash of content + config
• File-based caching: Stores serialized DocumentNode in system temp directory with configurable TTL (default 24 hours)
• In-memory caching: Deduplicates parse requests within the same render process
• Smart cache key: Includes file contents, path, initial header level, and root flag

Performance Impact

~40% parse time reduction for unchanged files during incremental builds.

Technical Details

• Decorator pattern: CachingParseFileHandler wraps existing ParseFileHandler
• PHP 8.1 compatible
• Cache location: {sys_temp_dir}/typo3-guides-ast-cache/
• Serialized PHP objects with class allowlisting
• TTL validation prevents stale cache usage

Part of Performance Initiative

This is Phase 1.2 of the performance optimization initiative tracked in #1143.

Related PRs:

• #1152 - Inventory caching (Phase 1.1)

Upstream dependencies (phpdocumentor/guides):

• #1287 - DocumentEntryNode file path method
• #1288 - DocumentEntryNode isRoot flag
• #1289 - ProjectNode find method
• #1293 - O(1) document lookup optimization

Test plan

• Run render on documentation project
• Verify AST cache files created in temp directory
• Modify source file and verify re-parse occurs
• Leave file unchanged and verify cache hit
• Test cache expiration after TTL